~ chicken-core (master) /manual/Module (chicken memory representation)
Trap1[[tags: manual]]2[[toc:]]34== Module (chicken memory representation)56The procedures from this module operate on the in-memory7representation of Scheme objects. These procedures ''are'' safe, so,8for example, unlike the procedures from {{(chicken memory)}} these9procedures ''will'' type-check and range-check their arguments, but10you still need to know what you're doing because the effects may be11surprising for the uninitiated.121314=== Extending procedures with data151617==== extend-procedure1819<procedure>(extend-procedure PROCEDURE X)</procedure>2021Returns a copy of the procedure {{PROCEDURE}} which contains an22additional data slot initialized to {{X}}. If {{PROCEDURE}} is already23an extended procedure, then its data slot is changed to contain {{X}}24and the same procedure is returned. Signals an error when25{{PROCEDURE}} is not a procedure.262728==== extended-procedure?2930<procedure>(extended-procedure? PROCEDURE)</procedure>3132Returns {{#t}} if {{PROCEDURE}} is an extended procedure,33or {{#f}} otherwise.343536==== procedure-data3738<procedure>(procedure-data PROCEDURE)</procedure>3940Returns the data object contained in the extended procedure41{{PROCEDURE}}, or {{#f}} if it is not an extended procedure.424344==== set-procedure-data!4546<procedure>(set-procedure-data! PROCEDURE X)</procedure>4748Changes the data object contained in the extended procedure49{{PROCEDURE}} to {{X}}. Signals an error when {{PROCEDURE}} is not an50extended procedure.5152<enscript highlight=scheme>53(define foo54 (letrec ((f (lambda () (procedure-data x)))55 (x #f) )56 (set! x (extend-procedure f 123))57 x) )58(foo) ==> 12359(set-procedure-data! foo 'hello)60(foo) ==> hello61</enscript>62636465=== Low-level data access6667These procedures operate with what are known as ''vector-like68objects''. A ''vector-like object'' is a vector, record structure,69pair, symbol or keyword: it is an aggregation of other Scheme objects.7071Note that strings and bytevectors are not considered vector-like (they are72considered to be ''byte vectors'', which are objects of mostly73unstructured binary data).747576==== vector-like?7778<procedure>(vector-like? X)</procedure>7980Returns {{#t}} when {{X}} is a vector-like object, returns {{#f}}81otherwise.828384==== block-ref8586<procedure>(block-ref VECTOR* INDEX)</procedure>8788Returns the contents of the {{INDEX}}th slot of the vector-like object89{{VECTOR*}}.909192==== block-set!9394<procedure>(block-set! VECTOR* INDEX X)</procedure><br>95<procedure>(set! (block-ref VECTOR* INDEX) X)</procedure>9697Sets the contents of the {{INDEX}}th slot of the vector-like object98{{VECTOR*}} to the value of {{X}}.99100==== number-of-slots101102<procedure>(number-of-slots VECTOR*)</procedure>103104Returns the number of slots that the vector-like object {{VECTOR*}}105contains.106107108==== number-of-bytes109110<procedure>(number-of-bytes BLOCK)</procedure>111112Returns the number of bytes that the object {{BLOCK}}113holds. {{BLOCK}} may be any non-immediate value. For strings and symbols, the size114of the buffer holding the encoded characters is returned.115116117==== object-copy118119<procedure>(object-copy X)</procedure>120121Copies {{X}} recursively and returns the fresh copy. Objects allocated122in static memory are copied back into garbage collected storage.123124125==== number-vector-data126127<procedure>(number-vector-data VECTOR)</procedure>128129Returns the bytevector holding the raw data of the numeric vector {{VECTOR}},130which should be a bytevector or a homogenous number vector as those131exposed by the {{(chicken numvector)}} and {{srfi-4}} library modules.132If {{VECTOR}} is a bytevector, the result will be identical to the argument.133The returned bytevector shares storage with the original value.134135136=== Record instance137138139==== make-record-instance140141<procedure>(make-record-instance SYMBOL ARG1 ...)</procedure>142143Returns a new instance of the record type {{SYMBOL}}, with its144slots initialized to {{ARG1 ...}}. To illustrate:145146<enscript highlight=scheme>147(define-record-type point (make-point x y) point?148 (x point-x point-x-set!)149 (y point-y point-y-set!))150</enscript>151152expands into something quite similar to:153154<enscript highlight=scheme>155(begin156 (define (make-point x y)157 (make-record-instance 'point x y) )158 (define (point? x)159 (and (record-instance? x)160 (eq? 'point (block-ref x 0)) ) )161 (define (point-x p) (block-ref p 1))162 (define (point-x-set! p x) (block-set! p 1 x))163 (define (point-y p) (block-ref p 2))164 (define (point-y-set! p y) (block-set! p 1 y)) )165</enscript>166167168==== record-instance?169170<procedure>(record-instance? X [SYMBOL])</procedure>171172Returns {{#t}} if {{X}} is a record structure, or {{#f}} otherwise.173174Further, returns {{#t}} if {{X}} is of type {{SYMBOL}}, or {{#f}}175otherwise.176177178==== record-instance-type179180<procedure>(record-instance-type RECORD)</procedure>181182Returns type symbol of the record structure {{RECORD}}. Signals an183error if {{RECORD}} is not a record structure.184185186==== record-instance-length187188<procedure>(record-instance-length RECORD)</procedure>189190Returns number of slots for the record structure {{RECORD}}. The191record-instance type is not counted. Signals an error if192{{RECORD}} is not a record structure.193194195==== record-instance-slot196197<procedure>(record-instance-slot RECORD INDEX)</procedure>198199Returns the contents of the {{INDEX}}th slot of the record structure200{{RECORD}}. The slot index range is the open interval {{[0201record-instance-length)}}. Signals an error if {{RECORD}} is not a record202structure.203204205==== record-instance-slot-set!206207<procedure>(record-instance-slot-set! RECORD INDEX X)</procedure><br>208<procedure>(set! (record-instance-slot RECORD INDEX) X)</procedure>209210Sets the {{INDEX}}th slot of the record structure {{RECORD}} to211{{X}}. The slot index range is the open interval {{[0212record-instance-length)}}. Signals an error if {{RECORD}} is not a213record structure.214215216==== record->vector217218<procedure>(record->vector RECORD)</procedure>219220Returns a new vector with the type and the elements of the record221structure {{RECORD}}. Signals an error if {{RECORD}} is not a record222structure.223224225=== Magic226227228==== object-become!229230<procedure>(object-become! ALIST)</procedure>231232Changes the identity of the value of the car of each pair in {{ALIST}}233to the value of the cdr. Neither value may be immediate (i.e. exact234integers, characters, booleans or the empty list).235236<enscript highlight=scheme>237(define x "i used to be a string")238(define y '#(and now i am a vector))239(object-become! (list (cons x y)))240x ==> #(and now i am a vector)241y ==> #(and now i am a vector)242(eq? x y) ==> #t243</enscript>244245Note: this operation invokes a major garbage collection.246247The effect of using {{object-become!}} on evicted data (see248{{object-evict}}) is undefined.249250251==== mutate-procedure!252253<procedure>(mutate-procedure! OLD PROC)</procedure>254255Replaces the procedure {{OLD}} with the result of calling the256one-argument procedure {{PROC}}. {{PROC}} will receive a copy of257{{OLD}} that will be identical in behaviour to the result of {{OLD}}:258259<enscript highlight=scheme>260 ;;; Replace arbitrary procedure with tracing one:261262 (mutate-procedure! my-proc263 (lambda (new)264 (lambda args265 (printf "~s called with arguments: ~s~%" new args)266 (apply new args) ) ) )267</enscript>268269270---271Previous: [[Module (chicken memory)]]272273Next: [[Module (chicken module)]]